/*
 * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang.reflect;

/**
 * {@code InvocationHandler} 是代理实例的<i>调用处理器</i>所实现的接口。
 *
 * <p>每个代理实例都有一个关联的调用处理器。
 * 当在代理实例上调用方法时，方法调用被编码并分派到其调用处理器的 {@code invoke} 方法。
 *
 * @author      Peter Jones
 * @see         Proxy
 * @since       1.3
 */
public interface InvocationHandler {

    /**
     * 处理代理实例上的方法调用并返回结果。
     * 当在与调用处理器关联的代理实例上调用方法时，将在调用处理器上调用此方法。
     *
     * @param   proxy 调用方法的代理实例
     *
     * @param   method 对应于在代理实例上调用的接口方法的 {@code Method} 实例。
     * {@code Method} 对象的声明类将是声明该方法的接口，
     * 该接口可能是代理类通过继承获得该方法的代理接口的超接口。
     *
     * @param   args 包含传递给代理实例上方法调用的参数值的对象数组，
     * 如果接口方法不接受参数，则为 {@code null}。
     * 基本类型的参数被包装在相应的基本包装类的实例中，
     * 例如 {@code java.lang.Integer} 或 {@code java.lang.Boolean}。
     *
     * @return  从代理实例上的方法调用返回的值。
     * 如果接口方法的声明返回类型是基本类型，
     * 则此方法返回的值必须是相应基本包装类的实例；
     * 否则，它必须是可分配给声明返回类型的类型。
     * 如果此方法返回的值是 {@code null} 且接口方法的返回类型是基本类型，
     * 则代理实例上的方法调用将抛出 {@code NullPointerException}。
     * 如果此方法返回的值与接口方法的声明返回类型不兼容（如上所述），
     * 则代理实例上的方法调用将抛出 {@code ClassCastException}。
     *
     * @throws  Throwable 从代理实例上的方法调用抛出的异常。
     * 异常的类型必须可分配给接口方法的 {@code throws} 子句中声明的任何异常类型，
     * 或者可分配给未检查异常类型 {@code java.lang.RuntimeException}
     * 或 {@code java.lang.Error}。
     * 如果此方法抛出的检查异常不可分配给接口方法的 {@code throws} 子句中
     * 声明的任何异常类型，则代理实例上的方法调用将抛出包含此方法抛出的异常的
     * {@link UndeclaredThrowableException}。
     *
     * @see     UndeclaredThrowableException
     */
    public Object invoke(Object proxy, Method method, Object[] args)
        throws Throwable;
}
